/*
 * Copyright 2009 Armando Blancas
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package taskgraph.ports;

import java.io.EOFException;
import java.io.IOException;

/**
 * An input interface to a Byte Channel.
 * 
 * @author Armando Blancas
 */
public interface ByteInputPort extends Port {
	
    /**
     * Reads and returns one input byte. The byte is treated as a signed value 
     * in the range <code>-128</code> through <code>127</code>, inclusive.
     * This method is suitable for reading the byte written by the <code>
     * writeByte</code> method of interface <code>DataOutput</code>.
     *
     * @return The 8-bit value read.
     * @throws EOFException If the channel reaches the end before reading
     *         all the bytes.
     * @throws IOException If an I/O error occurs.
     */
    byte read() throws IOException;

    /**
     * Reads into an array of bytes.
     * 
     * Reads bytes from the channel and stores them into the buffer array <code>
     * b</code>. The number of bytes read is the length of <code>b</code>. 
     * <p>This method blocks until one of the following conditions occurs:<p>
     * <ul><li><code>b.length</code> bytes of input data are available, in which
     * case a normal return is made.
     * <li>End of file is detected, in which case an <code>EOFException</code>
     * is thrown.
     * <li>An I/O error occurs, in which case an <code>IOException</code> other
     * than <code>EOFException</code> is thrown.
     * </ul>
     * <p>If <code>b</code> is <code>null</code>, a <code>NullPointerException
     * </code> is thrown. If <code>b.length</code> is zero, then no bytes are 
     * read. Otherwise, the first byte read is stored into element <code>b[0]
     * </code>, the next one into <code>b[1]</code>, and so on.
     * If an exception is thrown from this method, then it may be that some but
     * not all bytes of <code>b</code> have been updated with data from the 
     * channel.
     *
     * @param b The buffer into which the data is read.
     * @return The number of bytes read.
     * @throws EOFException If this channel reaches the end before reading
     *         all the bytes.
     * @throws IOException  If an I/O error occurs.
     */
    int read(byte[] b) throws IOException;

    /**
     * Reads into an array of bytes.
     * 
     * Reads <code>len</code> bytes from the channel.
     * <p>This method blocks until one of the following conditions occurs:
     * <p><ul><li><code>len</code> bytes of input data are available, in which 
     * case a normal return is made.
     * <li>End of file is detected, in which case an <code>EOFException</code>
     * is thrown.
     * <li>An I/O error occurs, in which case an <code>IOException</code> other
     * than <code>EOFException</code> is thrown.
     * </ul><p>If <code>b</code> is <code>null</code>, a 
     * <code>NullPointerException</code> is thrown. If <code>off</code> is 
     * negative, or <code>len</code> is negative, or <code>off+len</code> is
     * greater than the length of the array <code>b</code>, then an 
     * <code>IndexOutOfBoundsException</code> is thrown. If <code>len</code> 
     * is zero, then no bytes are read. Otherwise, the first byte read is stored
     * into element {@code b[off]}, the next one into {@code b[off+1]},
     * and so on. The number of bytes read is, at most, equal to {@code len}.
     *
     * @param b    The buffer into which the data is read.
     * @param off  An int specifying the offset into the data.
     * @param len  An int specifying the number of bytes to read.
     * @return The number of bytes read.
     * @throws EOFException If the channel reaches the end before reading
     *         all the bytes.
     * @throws IOException If an I/O error occurs.
     */
    int read(byte[] b, int off, int len) throws IOException;

    /**
     * Discards a number of bytes from the buffer.
     * 
     * Makes an attempt to skip over <code>n</code> bytes of data from the
     * channel, discarding the skipped bytes. However, it may skip over some 
     * smaller number of bytes, possibly zero. This may result from any of a
     * number of conditions; reaching end of channel before {@code n} bytes
     * have been skipped is only one possibility. This method never throws an 
     * {@code EOFException}. The actual number of bytes skipped is returned.
     *
     * @param n The number of bytes to be skipped.
     * @return The number of bytes actually skipped.
     * @throws IOException If an I/O error occurs.
     */
    int skipBytes(int n) throws IOException;

}
